home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / gemxx19.zoo / gem++19 / man / gemf.man < prev    next >
Text File  |  1993-08-24  |  6KB  |  154 lines
  1.                      GEM++ - C++ LIBRARIES FOR GEM/AES/VDI
  2.  
  3.  
  4.  
  5. NAME
  6.      GEMform - interacts with the user through a GEM form (dialog box).
  7.  
  8. DESCRIPTION
  9.      Forms or "dialog boxes" are objects which may interact with the
  10.      user.  The activities of the user may trigger events to be sent
  11.      to components of the GEMform.  GEMrawobjects are the components
  12.      of GEMforms, however, it is GEMobjects declared to be part of
  13.      a GEMform that are most interesting, and can be found by using
  14.      the Cook() method of a GEMrawobject for which a GEMobject has
  15.      been declared.
  16.  
  17. CONSTRUCTORS
  18.      GEMform(const GEMrsc& rsc, int RSCindex)
  19.        Create a form that is the form specified by the given index
  20.        in the given GEMrsc.
  21.  
  22.      GEMform(const GEMform&)
  23.        Create a copy of the given GEMform.  All parts of the form
  24.        are duplicated, except those that are sharable:
  25.  
  26.          The first (least significant) bits of the ExtendedType
  27.          define whether an object needs to have a new copy of
  28.          the object-specific data, or whether it is sharable.
  29.  
  30.          For EDITABLE objects, ExtendedType 0 indicates that the
  31.          user-input text of the object is not sharable - a duplicate
  32.          copy of the text is made.  ExtendedType 1 indicates that
  33.          the template and prompt text needs to be copied.
  34.          ExtendedType 2 indicates that all may be shared.
  35.          ExtendedType 3 indicates that user-input text can be
  36.          shared, but the prompt and template are to be copied.
  37.  
  38.          For non-EDITABLE objects, 0 indicates all shared,
  39.          1 indicates text shared, 2 indicates non-text shared,
  40.          and 3 indicates non shared.
  41.  
  42.          For icons, the "user-input" text is the label and
  43.          the "prompt" is the icon.
  44.  
  45.          This may seem fairly complicated at first, but basically
  46.          you can leave the ExtendedType set to 0 for most
  47.          applications.
  48.  
  49. METHODS
  50.      virtual int Do(int x, int y);
  51.        Conduct the interaction by drawing the form at the given
  52.        screen position until a component GEMobject signals for the
  53.        interaction to end (see GEMfeedback) or a part of the form
  54.        that is not declared as a GEMobject and that has the TOUCHEXIT
  55.        or EXIT flags set is clicked.  The RSC index of the object
  56.        that caused the exit is returned.
  57.      int Do()
  58.        As above, but centred.
  59.  
  60.      bool Zooms(bool b)
  61.        Disable or enable the "zoom" lines.  (default = disabled)
  62.  
  63.      bool Flight(bool b)
  64.        Enable/disable flying ability of this dialog.  Returns previous
  65.        state.  By default, TRUE.  Need only be disabled if memory is
  66.        at a premium when the dialog is being displayed.
  67.  
  68.      void Fly(bool opaque=TRUE)
  69.        If flight is enabled, this method causes flight to occur.
  70.        For example, the action of DoItem() when any non-interesting
  71.        item is chosen may be to call this method.  Does nothing is
  72.        Flight is disabled.  Note that if memory could not be allocated
  73.        during form display, this will do nothing.
  74.  
  75.      virtual void RedrawObject(int RSCindex)
  76.        Redraw the given object in the form.
  77.  
  78.      virtual void RedrawObject(int RSCindex,int Cx,int Cy,int Cw,int Ch)
  79.        Redraw the given object in the form, clipped as specified.
  80.  
  81.      int Parent(int RSCindex) const
  82.        Return the RSCindex of the parent of the object with the
  83.        given RSCindex.
  84.  
  85.      GEMrawobject* operator[](int RSCindex) const;
  86.        Return the component with the given RSCindex.  Often the
  87.        Cook() method of this GEMrawobject will be called.
  88.  
  89.      void AlignObject(int RSCindex, int xmult=8, int ymult=1)
  90.        Some objects, especially text, redraw faster when then are byte-
  91.        or word-aligned on the screen.  This method sets the alignment
  92.        for the window such that the given object is positioned at a
  93.        multiple of the given coordinates.
  94.  
  95.      int Map(int Do(GEMrawobject* tree, int obj),
  96.              bool skiphidden=TRUE, int RSCfrom=0, int RSCto=-1)
  97.        Call the given function for each object in this form such that
  98.        tree[obj] is the object, starting from RSCfrom, ending at RSCto
  99.        or end-of-tree.  If objects with HideTree() TRUE are to be
  100.        trasparently skipped, set skiphidden to TRUE (default).  The
  101.        function should return -1 if the search should continue into
  102.        the subtrees of the object, -2 if the search should skip the
  103.        subtrees (continuing to siblings), or a non-negative value,
  104.        which immediately terminates the search.  Map() returns the
  105.        value of the last call to the parametric Do() function.
  106.  
  107.      int Index() const
  108.        Returns the RSCindex from which the form was created.
  109.  
  110. EXTENSION METHODS
  111.      GEMrawobject *Obj
  112.        The actual GEM tree.
  113.  
  114.      virtual int FormDo()
  115.        Perform the functions of the standard GEM form_do() function
  116.        See GEMhotform for an example use of this.
  117.  
  118.      virtual GEMfeedback DoItem(int item, const GEMevent& e)
  119.        Called by Do() when objects are touched.  Standard function calls
  120.        the Touch() member of the GEMobject (if the GEMrawobject can
  121.        be Cook()ed).  Overriding this method provides a simple form-level
  122.        click handler.  Normally, any override of this method would
  123.        pass on control to the standard GEMform::DoItem(...) so that
  124.        any GEMobjects declared in the form are triggered.
  125.  
  126. EXAMPLES
  127.      {
  128.          GEMapplication appl;
  129.          GEMrsc rsc("foo.rsc");
  130.          GEMform form(rsc,FORM_RSC_INDEX);
  131.          form.Do();
  132.      }
  133.  
  134. SEE ALSO
  135.      GEMobject, GEMrawobject, GEMhotform
  136.  
  137. BUGS
  138.      Bugs in GEM++ should be reported to warwick@cs.uq.oz.au
  139.  
  140. AUTHOR
  141.      Warwick Allison, 1993.
  142.      warwick@cs.uq.oz.au
  143.  
  144. COPYING
  145.      This functionality is part of the GEM++ library,
  146.      and is Copyright 1993 by Warwick W. Allison.
  147.  
  148.      GEM++ is free and protected under the GNU Library General Public
  149.      License.
  150.  
  151.      You are free to copy and modify these sources, provided you
  152.      acknowledge the origin by retaining this notice, and adhere to
  153.      the conditions described in the GNU LGPL.
  154.